home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Applications 2002 November / SGI IRIX 6.5 Applications 2002 November.iso / dev / java2v131_02_dev.idb / usr / java2v131_02 / include / jawt.h.z / jawt.h
Encoding:
C/C++ Source or Header  |  2002-06-19  |  7.4 KB  |  257 lines
  1. /*
  2.  * @(#)jawt.h    1.5 00/02/02
  3.  *
  4.  * Copyright 1999, 2000 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the proprietary information of Sun Microsystems, Inc.  
  7.  * Use is subject to license terms.
  8.  * 
  9.  */
  10.  
  11. #ifndef _JAVASOFT_JAWT_H_
  12. #define _JAVASOFT_JAWT_H_
  13.  
  14. #include "jni.h"
  15.  
  16. #ifdef __cplusplus
  17. extern "C" {
  18. #endif
  19.  
  20. /*
  21.  * AWT native interface (new in JDK 1.3)
  22.  *
  23.  * The AWT native interface allows a native C or C++ application a means
  24.  * by which to access native structures in AWT.  This is to facilitate moving
  25.  * legacy C and C++ applications to Java and to target the needs of the
  26.  * community who, at present, wish to do their own native rendering to canvases
  27.  * for performance reasons.  Standard extensions such as Java3D also require a
  28.  * means to access the underlying native data structures of AWT.
  29.  *
  30.  * There may be future extensions to this API depending on demand.
  31.  *
  32.  * A VM does not have to implement this API in order to pass the JCK.
  33.  * It is recommended, however, that this API is implemented on VMs that support
  34.  * standard extensions, such as Java3D.
  35.  *
  36.  * Since this is a native API, any program which uses it cannot be considered
  37.  * 100% pure java.
  38.  */
  39.  
  40. /*
  41.  * AWT Native Drawing Surface (JAWT_DrawingSurface).
  42.  *
  43.  * For each platform, there is a native drawing surface structure.  This
  44.  * platform-specific structure can be found in jawt_md.h.  It is recommended
  45.  * that additional platforms follow the same model.  It is also recommended
  46.  * that VMs on Win32 and Solaris support the existing structures in jawt_md.h.
  47.  *
  48.  *******************
  49.  * EXAMPLE OF USAGE:
  50.  *******************
  51.  *
  52.  * In Win32, a programmer wishes to access the HWND of a canvas to perform
  53.  * native rendering into it.  The programmer has declared the paint() method
  54.  * for their canvas subclass to be native:
  55.  *
  56.  *
  57.  * MyCanvas.java:
  58.  *
  59.  * import java.awt.*;
  60.  *
  61.  * public class MyCanvas extends Canvas {
  62.  *
  63.  *     static {
  64.  *         System.loadLibrary("mylib");
  65.  *     }
  66.  *
  67.  *     public native void paint(Graphics g);
  68.  * }
  69.  *
  70.  *
  71.  * myfile.c:
  72.  *
  73.  * #include "jawt_md.h"
  74.  * #include <assert.h>
  75.  *
  76.  * JNIEXPORT void JNICALL
  77.  * Java_MyCanvas_paint(JNIEnv* env, jobject canvas, jobject graphics)
  78.  * {
  79.  *     JAWT awt;
  80.  *     JAWT_DrawingSurface* ds;
  81.  *     JAWT_DrawingSurfaceInfo* dsi;
  82.  *     JAWT_Win32DrawingSurfaceInfo* dsi_win;
  83.  *     jboolean result;
  84.  *     jint lock;
  85.  *
  86.  *     // Get the AWT
  87.  *     awt.version = JAWT_VERSION_1_3;
  88.  *     result = JAWT_GetAWT(env, &awt);
  89.  *     assert(result != JNI_FALSE);
  90.  *
  91.  *     // Get the drawing surface
  92.  *     ds = awt.GetDrawingSurface(env, canvas);
  93.  *     assert(ds != NULL);
  94.  *
  95.  *     // Lock the drawing surface
  96.  *     lock = ds->Lock(ds);
  97.  *     assert((lock & JAWT_LOCK_ERROR) == 0);
  98.  *
  99.  *     // Get the drawing surface info
  100.  *     dsi = ds->GetDrawingSurfaceInfo(ds);
  101.  *
  102.  *     // Get the platform-specific drawing info
  103.  *     dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;
  104.  *
  105.  *     //////////////////////////////
  106.  *     // !!! DO PAINTING HERE !!! //
  107.  *     //////////////////////////////
  108.  *
  109.  *     // Free the drawing surface info
  110.  *     ds->FreeDrawingSurfaceInfo(dsi);
  111.  *
  112.  *     // Unlock the drawing surface
  113.  *     ds->Unlock(ds);
  114.  *
  115.  *     // Free the drawing surface
  116.  *     awt.FreeDrawingSurface(ds);
  117.  * }
  118.  *
  119.  */
  120.  
  121. /*
  122.  * JAWT_Rectangle
  123.  * Structure for a native rectangle.
  124.  */
  125. typedef struct jawt_Rectangle {
  126.     jint x;
  127.     jint y;
  128.     jint width;
  129.     jint height;
  130. } JAWT_Rectangle;
  131.  
  132. struct jawt_DrawingSurface;
  133.  
  134. /*
  135.  * JAWT_DrawingSurfaceInfo
  136.  * Structure for containing the underlying drawing information of a component.
  137.  */
  138. typedef struct jawt_DrawingSurfaceInfo {
  139.     /*
  140.      * Pointer to the platform-specific information.  This can be safely
  141.      * cast to a JAWT_Win32DrawingSurfaceInfo on Windows or a
  142.      * JAWT_X11DrawingSurfaceInfo on Solaris.  See jawt_md.h for details.
  143.      */
  144.     void* platformInfo;
  145.     /* Cached pointer to the underlying drawing surface */
  146.     struct jawt_DrawingSurface* ds;
  147.     /* Bounding rectangle of the drawing surface */
  148.     JAWT_Rectangle bounds;
  149.     /* Number of rectangles in the clip */
  150.     jint clipSize;
  151.     /* Clip rectangle array */
  152.     JAWT_Rectangle* clip;
  153. } JAWT_DrawingSurfaceInfo;
  154.  
  155. #define JAWT_LOCK_ERROR                 0x00000001
  156. #define JAWT_LOCK_CLIP_CHANGED          0x00000002
  157. #define JAWT_LOCK_BOUNDS_CHANGED        0x00000004
  158. #define JAWT_LOCK_SURFACE_CHANGED       0x00000008
  159.  
  160. /*
  161.  * JAWT_DrawingSurface
  162.  * Structure for containing the underlying drawing information of a component.
  163.  * All operations on a JAWT_DrawingSurface MUST be performed from the same
  164.  * thread as the call to GetDrawingSurface.
  165.  */
  166. typedef struct jawt_DrawingSurface {
  167.     /*
  168.      * Cached reference to the Java environment of the calling thread.
  169.      * If Lock(), Unlock(), GetDrawingSurfaceInfo() or
  170.      * FreeDrawingSurfaceInfo() are called from a different thread,
  171.      * this data member should be set before calling those functions.
  172.      */
  173.     JNIEnv* env;
  174.     /* Cached reference to the target object */
  175.     jobject target;
  176.     /*
  177.      * Lock the surface of the target component for native rendering.
  178.      * When finished drawing, the surface must be unlocked with
  179.      * Unlock().  This function returns a bitmask with one or more of the
  180.      * following values:
  181.      *
  182.      * JAWT_LOCK_ERROR - When an error has occurred and the surface could not
  183.      * be locked.
  184.      *
  185.      * JAWT_LOCK_CLIP_CHANGED - When the clip region has changed.
  186.      *
  187.      * JAWT_LOCK_BOUNDS_CHANGED - When the bounds of the surface have changed.
  188.      *
  189.      * JAWT_LOCK_SURFACE_CHANGED - When the surface itself has changed
  190.      */
  191.     jint (JNICALL *Lock)
  192.         (struct jawt_DrawingSurface* ds);
  193.     /*
  194.      * Get the drawing surface info.
  195.      * The value returned may be cached, but the values may change if
  196.      * additional calls to Lock() or Unlock() are made.
  197.      * Lock() must be called before this can return a valid value.
  198.      * Returns NULL if an error has occurred.
  199.      * When finished with the returned value, FreeDrawingSurfaceInfo must be
  200.      * called.
  201.      */
  202.     JAWT_DrawingSurfaceInfo* (JNICALL *GetDrawingSurfaceInfo)
  203.         (struct jawt_DrawingSurface* ds);
  204.     /*
  205.      * Free the drawing surface info.
  206.      */
  207.     void (JNICALL *FreeDrawingSurfaceInfo)
  208.         (JAWT_DrawingSurfaceInfo* dsi);
  209.     /* 
  210.      * Unlock the drawing surface of the target component for native rendering.
  211.      */
  212.     void (JNICALL *Unlock)
  213.         (struct jawt_DrawingSurface* ds);
  214. } JAWT_DrawingSurface;
  215.  
  216. /*
  217.  * JAWT
  218.  * Structure for containing native AWT functions.
  219.  */
  220. typedef struct jawt {
  221.     /*
  222.      * Version of this structure.  This must always be set before
  223.      * calling JAWT_GetAWT()
  224.      */
  225.     jint version;
  226.     /*
  227.      * Return a drawing surface from a target jobject.  This value
  228.      * may be cached.
  229.      * Returns NULL if an error has occurred.
  230.      * Target must be a java.awt.Canvas.
  231.      * FreeDrawingSurface() must be called when finished with the
  232.      * returned JAWT_DrawingSurface.
  233.      */
  234.     JAWT_DrawingSurface* (JNICALL *GetDrawingSurface)
  235.         (JNIEnv* env, jobject target);
  236.     /*
  237.      * Free the drawing surface allocated in GetDrawingSurface.
  238.      */
  239.     void (JNICALL *FreeDrawingSurface)
  240.         (JAWT_DrawingSurface* ds);
  241. } JAWT;
  242.  
  243. /*
  244.  * Get the AWT native structure.  This function returns JNI_FALSE if
  245.  * an error occurs.
  246.  */
  247. _JNI_IMPORT_OR_EXPORT_
  248. jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt);
  249.  
  250. #define JAWT_VERSION_1_3 0x00010003
  251.  
  252. #ifdef __cplusplus
  253. } /* extern "C" */
  254. #endif
  255.  
  256. #endif /* !_JAVASOFT_JAWT_H_ */
  257.